[% setvar title Exception objects and classes for builtins %]
<div id="archive-notice">
    <h3>This file is part of the Perl 6 Archive</h3>
    <p>To see what is currently happening visit <a href="http://www.perl6.org/">http://www.perl6.org/</a></p>
</div>
<div class='pod'>
<a name='TITLE'></a><h1>TITLE</h1>
<p>Exception objects and classes for builtins</p>
<a name='VERSION'></a><h1>VERSION</h1>
<pre>  Maintainer: Peter Scott &lt;<a href='mailto:peter@psdt.com'>peter@psdt.com</a>&gt;
  Date: 9 Aug 2000
  Last Modified: 3 Oct 2000
  Mailing List: <a href='mailto:perl6-language-errors@perl.org'>perl6-language-errors@perl.org</a>
  Number: 80
  Version: 4
  Status: Frozen</pre>
<a name='ABSTRACT'></a><h1>ABSTRACT</h1>
<p>This RFC proposes that builtins that throw exceptions throw them as objects
belonging to a set of standard classes.  This would enable an exception
type to be easily recognized by user code.  The behavior if the exception
were not trapped should be identical to the current behavior (error message
with optional line number output to STDERR and exit with non-zero exit code).</p>
<a name='DESCRIPTION'></a><h1>DESCRIPTION</h1>
<p>This RFC is tightly bound with RFC 88, which proposes an exception handling
mechanism based upon exceptions-as-objects, and in particular specifies
that fatal exceptions thrown by the core will be objects with certain
instance attributes.  We assume here that these aspects of RFC 88 are
implemented.</p>
<p>Builtins experiencing fatal errors currently call <code>die</code>, which is to say,
they throw an exception.  Builtins experiencing non-fatal errors return a
variety of error codes.  RFC 70 proposes that these be trappable exceptions
if <code>use Fatal</code> is in effect.</p>
<p>This RFC proposes that both exceptions be objects blessed into a standard
set of classes which can be checked for by the user.</p>
<a name='Object Attributes'></a><h2>Object Attributes</h2>
<p>The exception object will have attributes filled in by perl.  The
applicable attributes from RFC 88 will be used, including:</p>
<ul>
<li><a name='tag'></a>tag</li>
<p>RFC 88 eschews numeric codes in favor of alphanumeric tags.  A system
exception should place the symbolic errno constant here, e.g., <code>EINVAL</code>,
for system errors; something will have to be made up for errors that don't
have associated errnos.</p>
<li><a name='message'></a>message</li>
<p>The text of the exception, e.g., &quot;Out of memory&quot;.</p>
<li><a name='severity'></a>severity</li>
<p>Relative level of fatality.  Chosen from some TBD enumeration, e.g.,
&quot;Warning&quot;, &quot;Fatal&quot;, &quot;Information&quot;.</p>
<li><a name='sysmsg'></a>sysmsg</li>
<p>Additional information about the exception, the kind of thing currently put
in <code>$^E</code>.</p>
<li><a name='files'></a>files</li>
<p>This and the next two attributes are used to track the program locations
the exception has passed through to this point since it was thrown.  This
attribute returns an array of filenames, starting with the one in which the
exception was thrown.  This is to preserve <code>caller</code>-type information for
the catcher to be able to see.  RFC 88 proposes the method <code>show</code> and
option <code>trace</code> to retrieve filenames and line numbers.</p>
<li><a name='lines'></a>lines</li>
<p>An array of line numbers of program locations the exception has passed
through between being thrown and being caught.</p>
<li><a name='subs'></a>subs</li>
<p>An array of (package-qualified) subroutine names the exception has passed
through between being thrown and being caught.</p>
</ul>
<p>Stringifying the object itself will yield the <code>message</code> attribute.  A
<code>facility</code> attribute was suggested to indicate what part of perl is
throwing the exception: IMO that is part of the exception class.  In an
numeric context, the value will be the <code>errno</code> if it corresponds to one,
otherwise up to the implementor.</p>
<a name='Classes'></a><h2>Classes</h2>
<p>This is a strawman exception class enumeration.  The merits of this RFC do
not depend on this being a good list, only on it being possible to
find a reasonable one.  A common prefix like <code>Exception::</code> is elided for
readability.</p>
<p>Note: conceivably, the implementation could allow an exception to belong to
more than one class at a time through multiple inheritance (e.g., <code>Regex</code>
and <code>Recursion</code>).  I haven't explored the ramifications of that.</p>
<p>These class names can be specified in calls to <code>Fatal.pm</code> (and appropriate
language currently appears in RFC 70), qualified with a <code>:</code> to distinguish
them from core function names.  This allows the user to change the fatality
or otherwise of whole classes of exceptions.  It would be possible (whether
it would also be <i>desirable</i> is another matter) for a user to say, e.g.,
<code>no Fatal qw(:Reference)</code> and thereby excise the usual core exception upon
an incorrect dereference operation, as though they had wrapped it in an
<code>eval</code>.  This makes the operation of <code>Fatal.pm</code> consistent over the
broadest possible application.</p>
<ul>
<li><a name='Arithmetic'></a>Arithmetic</li>
<p>Divide by zero and friends.</p>
<li><a name='Memory'></a>Memory</li>
<p><code>malloc</code> failed, request too large, that sort of thing.</p>
<li><a name='Eval'></a>Eval</li>
<p>A compilation error occurred in <code>eval</code>, <code>/e</code>, or <code>(?{ ... })</code>.  Possible
candidate for subdividing.</p>
<li><a name='Regex'></a>Regex</li>
<p>A syntax error occurred in a regex (built at run-time).  Possible candidate
for subdivision.</p>
<li><a name='IO'></a>IO</li>
<p>An I/O error occurred.  Almost certainly should be subdivided, perhaps
parallel to the <code>IO::</code> hierarchy.</p>
<li><a name='Format'></a>Format</li>
<p>Error in format given to <code>pack</code>, <code>printf</code>, octal/hex/binary number
etc.  Could use a better name.</p>
<li><a name='Thread'></a>Thread</li>
<p>Some goof in threading.</p>
<li><a name='Object'></a>Object</li>
<p>Tried to call non-existent method, that kind of thing.</p>
<li><a name='System'></a>System</li>
<p>Attempt to interact with external program failed (maybe it ran out of
process slots, that kind of thing).</p>
<li><a name='Taint'></a>Taint</li>
<p>Duh.</p>
<li><a name='Reference'></a>Reference</li>
<p>Attempt to dereference wrong kind of thing.</p>
<li><a name='Recursion'></a>Recursion</li>
<p>Excessive subroutine recursion, maybe also infinite <code>split</code> or <code>s///</code>
loops (although arguably they would throw a <code>Regex</code> exception).</p>
</ul>
<p>There are bound to be other categories that should be covered.  This
is just to put meat on the bones.  This is the province of librarians;
the fact that it's possible to argue endlessly about the choices doesn't
preclude coming up with good ones.</p>
<a name='IMPLEMENTATION'></a><h1>IMPLEMENTATION</h1>
<p>This should not be construed as requiring that clearly fatal errors (e.g.
pointer corrupted) should be trappable, or throw O-O exceptions.  Note that
compilation errors don't have to be classified.</p>
<a name='REFERENCES'></a><h1>REFERENCES</h1>
<p>RFC 70: Allow exception-based error-reporting.</p>
<p>RFC 85: All perl generated errors should have a unique identifier</p>
<p>RFC 88: Omnibus Structured Exception/Error Handling Mechanism</p>
<p>Error.pm (<code><a href='http://search.cpan.org/doc/GBARR/Error-0.13/Error.pm' target='_blank'>search.cpan.org</a></code>).</p>
<p><i><a href='http://search.cpan.org/perldoc?perldiag'>perldiag</a></i>.</p>
</div>
